# 用好 CLAUDE.md，让你的 AI 编程效率翻倍！

> 一份 Markdown 文件，让 AI 自动了解你的项目

大家好，我是程序员鱼皮。

最近我发现一个现象，很多同学开始用 Claude Code、Cursor 这些 AI 编程工具了，但用了一阵子之后就开始抱怨：AI 怎么总是不听话？让它改个 Bug 反而引入三个新 Bug，让它加个功能结果技术栈都给换了。

![](https://pic.yupi.icu/1/image-20260622164228939.png)

这些问题的根源，往往不是 AI 笨，而是你没有给它足够的上下文。

AI 每次开始新会话，都是一张白纸。它不知道你的项目用的是什么技术栈，不知道你们团队的代码规范，不知道你之前做了什么决策。

你不说，它就猜。猜对了算你运气好，猜错了你就得返工，把你的 tokens 全拿走，把回忆化成空~

那有没有一种方法，让 AI 每次开始工作前就自动了解你的项目？

必须有啊！就是今天要聊的 **CLAUDE.md**。

![](https://pic.yupi.icu/1/image-20260320152009626.png)



## 一、CLAUDE.md 是什么？

CLAUDE.md 是 Claude Code 里的一个 Markdown 文件，放在项目根目录下。

Claude Code 每次启动会话时，都会自动读取这个文件，把里面的内容当作项目的背景知识。

你可以把它理解为 **给 AI 写的「入职手册」**。就像新员工入职第一天，你会给他一份文档，介绍公司用什么技术、代码怎么写、测试怎么跑、有什么坑要注意。CLAUDE.md 干的就是这个事。

![](https://pic.yupi.icu/1/01_CLAUDE.md%E6%98%AFAI%E7%9A%84%E5%85%A5%E8%81%8C%E6%89%8B%E5%86%8C_compressed_v1.png)

比如一个最简单的 CLAUDE.md 长这样：

```markdown
# 我的博客系统

Next.js 16 + TypeScript + Tailwind CSS + Supabase

## 常用命令
- npm run dev        # 启动开发服务器
- npm run test       # 跑测试
- npm run build      # 生产构建

## 代码规范
- 使用函数式组件，不用 class 组件
- 样式只用 Tailwind CSS，不写自定义 CSS
- 所有组件必须有 TypeScript 类型定义
```

AI 每次开始工作前都会先读一遍，然后所有生成的代码都会自动遵循这些规范，不用你每次都重复交代。

不过有一点需要注意，CLAUDE.md 对 AI 来说 **是建议** 而 **不是强制执行** 的配置。它的效果取决于你写得有多具体、多简洁。越精确的指令 AI 遵循得越好，写了一大堆模糊的要求反而可能被选择性忽略。



## 二、更通用的 AGENTS.md

你可能会想，这是 Claude Code 的专属功能吗？我用 Cursor 怎么办？

其实几乎所有主流 AI 编程工具都有类似的机制。比如 Cursor 也支持 `.cursor/rules/` 和 AGENTS.md 来做同样的事。

必须要知道的是 AGENTS.md，它是一个跨工具的开放标准，由 OpenAI、Google、Cursor 等多家公司联合推出，目前已经有好万个开源项目在用，支持 30 多种 AI 编程工具。

![](https://pic.yupi.icu/1/image-20260622190311465.png)

Claude Code 虽然默认只读 CLAUDE.md，但你可以在 CLAUDE.md 里用一行 `@AGENTS.md` 把它导入进来，两边就打通了。

这些 Markdown 文件本质上都是一回事，就是 **给 AI 写一份项目说明书**。你学会写好这份说明书，换任何 AI 编程工具都能用。

而且 AGENTS.md 的用途不只是项目开发指导，它同样可以作为指导 AI 做事的工作流文档。比如我自己就用 AGENTS.md 来定义各种工作流，像图文创作、产品客服、数据分析这些场景，都可以用一份 Markdown 文件把 AI 的工作方式固定下来，每次启动自动加载，省得重复交代。

后面我会统一用 CLAUDE.md 来讲解，但里面的技巧对所有工具都适用。



## 三、为什么一定要写好这个文件？

你可能觉得，不就是个配置文件吗，随便写写不就行了？

大错特错！CLAUDE.md 的质量直接决定了 AI 帮你干活的效率和准确度。

以我自己天天用 AI 编程的体验来看，一个好的 CLAUDE.md 至少能解决 3 个问题：

**第一，减少重复沟通。** 

没有 CLAUDE.md 的时候，每次新会话我都得重复交代一遍技术栈、代码规范、项目结构。有了它，这些信息 AI 自动就知道了。

**第二，提升代码一致性。**

之前 AI 有时候用 React 函数组件，有时候给我整个 class 组件出来；有时候用 CSS Modules，有时候给我写内联样式。规范写进 CLAUDE.md 后，这种问题基本消失了。

**第三，降低出错率。**

比如我的项目里有个特殊的 API 响应格式 `{ success, data, error }`，不写进规则的话，AI 每次都按自己的习惯来。写进去之后，Claude 就会自动遵循，不用我每次纠正。

![](https://pic.yupi.icu/1/03_%E6%B2%A1%E6%9C%89vs%E6%9C%89CLAUDE.md%E7%9A%84%E5%AF%B9%E6%AF%94_compressed_v1.png)

之前我在另一篇文章里提到过，规则文件在 50 行左右时遵循率可以达到 94%，但如果一股脑堆到 400 行，遵循率就掉到了 71%。

**所以 CLAUDE.md 不是越多越好，而是要精准。**

这就引出了最核心的问题，也是本文的重点，怎么写好 CLAUDE.md 文档？



## 四、怎么写好 CLAUDE.md？

下面这些技巧，很多是经过社区大量实践和我个人验证的经验，建议仔细阅读，细细品味。



### 1、控制在 200 行以内

这是 Claude Code 官方文档给出的建议。

CLAUDE.md 的内容会在每次会话开始时加载到 AI 的上下文窗口中。这个窗口是有限的，你的规则文件越长，留给实际工作内容的空间就越少。

而且 AI 对指令的遵循能力跟指令数量负相关。社区有人引用过一项研究，AI 大概能合理遵循 150 到 200 条指令，超过这个数之后，遵循质量会均匀下降，不仅仅是忽略新加的，而且全部都开始变差。

**所以写 CLAUDE.md 要像写简历一样，精炼再精炼。**

![](https://pic.yupi.icu/1/08_%E6%8C%87%E4%BB%A4%E6%95%B0%E9%87%8Fvs%E9%81%B5%E5%BE%AA%E7%8E%87%E6%9B%B2%E7%BA%BF_compressed_v3.png)

对于每一行，问自己一个问题：删掉它 AI 会犯错吗？

如果答案是不会，就果断删掉。



### 2、只写 AI 猜不到的东西

官方文档专门列了一个 CLAUDE.md 中应该写和不该写的清单，非常值得参考。

应该写进去的：

- AI 不可能猜到的构建命令和测试命令
- 跟默认不同的代码风格规则
- 团队的 Git 规范（分支命名、PR 格式）
- 项目特有的架构决策
- 开发环境的特殊要求（必需的环境变量之类）
- 容易踩坑的地方

不该写进去的：
- AI 读代码就能知道的东西
- 通用的语言规范（AI 本来就会）
- 详细的 API 文档（放别的地方，CLAUDE.md 里放链接就行）
- 写干净的代码、注意性能这种废话

![](https://pic.yupi.icu/1/09_%E8%AF%A5%E5%86%99vs%E4%B8%8D%E8%AF%A5%E5%86%99%E5%88%86%E7%B1%BB%E7%AD%9B%E9%80%89%E5%9B%BE_compressed_v2.png)

像我做编程导航项目时，就把一些即使读代码也容易忽略的约定写进了 CLAUDE.md，比如 API 响应统一使用 `BaseResponse` 包装类、异常统一用 `BusinessException` 抛出。虽然 AI 深入分析代码也能发现这些模式，但写进规则之后能省掉它每次重新推断的过程，效率高很多。



### 3、用正面指令代替否定指令

这个技巧其实有点儿反直觉。。

有篇论文研究发现，87.5% 的 AI 规则违反都来自同一个原因，就是否定句反而把被禁止的概念给激活了。你写「不要使用分号」，AI 看到分号这两个字，反而更容易在后续生成中产出分号。

这跟心理学里的白熊效应一模一样。叫你不要想白熊，你脑子里马上就全是白熊。

所以正确的做法是用正面表述替代：
- ❌ 不要使用 class 组件 → ✅ 使用函数式组件和 Hooks
- ❌ 不要用 any 类型 → ✅ 所有变量必须有明确的 TypeScript 类型定义
- ❌ 不要在主分支直接提交 → ✅ 所有变更通过 feature 分支提交 PR

![](https://pic.yupi.icu/1/04_%E7%99%BD%E7%86%8A%E6%95%88%E5%BA%94%E4%B8%8E%E6%AD%A3%E9%9D%A2%E6%8C%87%E4%BB%A4_compressed_v2.png)



### 4、指令要具体可验证

模糊的指令等于没有指令。AI 很擅长处理具体的规则，但对抽象的要求就会自行发挥。

举些例子：

- ❌ 正确格式化代码 → ✅ 使用 2 空格缩进
- ❌ 测试你的更改 → ✅ 提交前运行 `npm test`
- ❌ 保持文件有序 → ✅ API handlers 放在 `src/api/handlers/`

越具体的指令，AI 越容易判断自己有没有遵循，违反了也更容易被发现。



### 5、用 Hooks 来强制执行

CLAUDE.md 本质上只是建议，不是 100% 生效的禁令。

像代码格式化、提交前跑测试、危险命令拦截这些任务，应该用确定性的自动化脚本来执行。

Claude Code 提供了 Hooks 机制，可以在 AI 操作的关键节点自动执行你预设的脚本。

比如你想让每次文件编辑后自动跑 ESLint，写一个 Hooks 配置就搞定了，AI 根本不介入，100% 会执行。

**一句话总结就是，CLAUDE.md 负责建议，Hooks 负责强制操作。**

![](https://pic.yupi.icu/1/05_CLAUDE.md%E5%BB%BA%E8%AE%AEvs_Hooks%E5%BC%BA%E5%88%B6%E6%89%A7%E8%A1%8C_compressed_v3.png)



### 6、大项目用路径规则按需加载

如果你的项目比较大，200 行根本装不下所有规范。这时候不要硬往 CLAUDE.md 里塞，而是用 `.claude/rules/` 目录来拆分。

每个规则文件可以用 YAML frontmatter 指定只对特定路径的文件生效：

```yaml
---
paths:
  - "src/api/**/*.ts"
---

# API 开发规范
- 所有 API 端点必须包含输入验证
- 使用标准的错误响应格式
- 添加 OpenAPI 文档注释
```

这样只有当 Claude 操作 `src/api/` 下面的 TypeScript 文件时，这些规则才会加载到上下文中，既省了上下文空间，又不会用不相关的规则干扰 AI。



### 7、用 @import 做渐进式披露

社区里最受推崇的高级技巧叫渐进式披露，核心思想就是不要把所有东西塞进 CLAUDE.md，而是告诉 AI 去哪里找它需要的信息。

做法很简单。在项目中创建一个 `docs/` 目录，放各类专题文档，然后在 CLAUDE.md 中用简短描述加触发条件来引用：

```markdown
## 参考文档

### API 架构 — @docs/api-architecture.md
何时阅读：添加或修改 API 端点时

### 数据库设计 — @docs/database-design.md
何时阅读：创建或修改数据模型时
```

这样 Claude 只在真正需要的时候才会去读取对应的文档，平时不占用上下文空间。

![](https://pic.yupi.icu/1/06_%E6%B8%90%E8%BF%9B%E5%BC%8F%E6%8A%AB%E9%9C%B2%E6%8C%89%E9%9C%80%E5%8A%A0%E8%BD%BD_compressed_v2.png)

CLAUDE.md 的 `@path` 导入语法支持相对路径和绝对路径，最多可以嵌套 4 层。

这个思路其实跟我之前讲的上下文工程和 Agent Skills 是类似的。AI 编程工具的上下文窗口是有限的，你不能一股脑把所有信息都塞进去。Anthropic 官方把这个策略叫 just-in-time，就是让 AI 按需获取信息，而不是全量加载。



### 8、让 AI 帮你维护

CLAUDE.md 不是写好了就不管了，它应该是一份随着项目成长不断完善的 "活" 文档。

Claude Code 的创始人推荐了一个习惯：**每次 Claude 犯错，不要只修正错误，还要顺手让它把纠正写进 CLAUDE.md。**

我自己也是这么做的，比如 Claude 用了错误的导入路径，纠正完之后跟它说一句：把这条规则更新到 CLAUDE.md 里，下次别再犯。

Claude 特别擅长给自己写规则，时间久了，你的 CLAUDE.md 就变成了一份完整的项目知识库，出错率会明显下降。

另外 Claude Code 现在还有一个 Auto Memory 自动记忆功能，Claude 会自动记录它在工作中发现的模式和偏好，存到 `~/.claude/projects/<项目>/memory/` 目录下。这些笔记每次会话都会自动加载，相当于 AI 给自己做了一份备忘录。

你随时可以用 `/memory` 命令查看和编辑这些记忆。

![](https://pic.yupi.icu/1/image-20260622182614045.png)



## 五、如何快速创建？

看到这里你可能会想，这些技巧我都记住了，但从零开始写一份完整的 CLAUDE.md 还是有点头疼。

别担心，有几个快速起步的方法。



### 用 /init 命令自动生成

在 Claude Code 中输入 `/init`，Claude 会自动分析你的代码库，生成一份包含构建命令、测试指令和项目规范的 CLAUDE.md。如果文件已经存在，它会建议改进而不是覆盖。

![](https://pic.yupi.icu/1/image-20260622182756786.png)

不过需要注意，自动生成的内容可能不够精确，毕竟 AI 只能看到你的代码成果，不理解背后的过程。

社区有人说过，CLAUDE.md 影响你工作流的每个阶段和产出的每个文件，一条不好的指令产生的破坏力远超一行坏代码。所以自动生成之后，一定要自己过一遍，该删的删、该补的补。



### 让 AI 从对话中沉淀

我自己经常用的一种方法是，先不急着写 CLAUDE.md，正常跟 AI 协作完成一两个任务。做完之后，让 AI 回顾整个对话过程，帮你总结出需要记住的项目规范和注意事项，直接写成 CLAUDE.md。

这样得到的规则文件是从实战中提炼出来的，比凭空想象要精准得多。

像我自己带团队做项目时，每次 Code Review 中发现 AI 犯的错误，都会让 Claude 把修正追加到 CLAUDE.md 里。做了一个月之后，这份文件已经沉淀了几十条非常有针对性的规则，新同事用 Claude Code 的时候上手也快了很多。

![](https://pic.yupi.icu/1/10_AI%E7%BA%A0%E9%94%99%E6%B2%89%E6%B7%80%E6%AD%A3%E5%90%91%E5%BE%AA%E7%8E%AF_compressed_v2.png)



### 参考优秀的开源项目

GitHub 上有个 awesome-claude-md 仓库，收录了 100 多个真实项目的 CLAUDE.md 示例，覆盖各种技术栈和项目类型，包括 Anthropic 官方的、Cloudflare 的 monorepo 项目等等。

另外还有个 awesome-claude-code 仓库，整理了 Skills、Hooks、斜杠命令等 Claude Code 生态工具，也值得收藏。

![](https://pic.yupi.icu/1/image-20260622184038586.png)

有时间的话，可以让 AI 帮你分析一下这些案例，找个跟你项目技术栈接近的参考着写，比从零开始快多了。

**记住，CLAUDE.md 的内容宁缺毋滥。**

先从最关键的 20 行开始，在实际使用中再慢慢补充。



## 六、多层级配置和团队协作

如果你在团队中使用 Claude Code，或者同时做多个项目，有一些进阶玩法值得了解。



### 四层作用域

CLAUDE.md 不只能放在项目根目录，它支持四个层级，按加载顺序从先到后排列：

1）组织级，公司 IT 统一部署的规范，所有人强制生效

2）用户级 `~/.claude/CLAUDE.md`，对你本机的所有项目生效

3）项目级 `./CLAUDE.md`，只对当前项目生效，可提交到 Git

4）本地级 `./CLAUDE.local.md`，只对当前项目生效，不提交到 Git

加载越靠后的内容，AI 越倾向于优先遵循，所以优先级是 本地级 > 项目级 > 用户级。但组织级比较特殊，它虽然加载最早，却 **不可被个人或项目设置排除**，属于公司强制执行的底线规范。

建议团队共享的规范写在项目级，个人偏好写在本地级，两边互不干扰。



### 团队共建 CLAUDE.md

Claude Code 的创始人推荐把 CLAUDE.md 用 Git 来管理，让团队成员共同维护。

每当有人在 Code Review 中发现 AI 犯了什么错误，就把修正追加到 CLAUDE.md 里。时间久了，这个文件就沉淀了团队的开发经验和规范，变成了整个团队的 AI 使用手册。

我们自己团队也是这么做的。像面试鸭后端项目的 AGENTS.md，里面沉淀了技术栈选型、Spring Boot 分层规范、统一响应格式、异常处理方式、数据库命名规则等约定。新同事入职直接看这份文件就能上手，Claude 也能自动遵循这些规范生成代码，省了大量沟通成本。

![](https://pic.yupi.icu/1/image-20260622183444669.png)



### 重要规则一定要存文件

当你在对话中用 `/compact` 压缩上下文时，项目根目录的 CLAUDE.md 会被重新读取和注入。但你在对话中口头说的指令，比如后面的代码都用 async/await，压缩后就没了。

所以，凡是重要的规则，一定要写进 CLAUDE.md，不要只在对话里说。这一点跟我之前讲的上下文工程也是相通的，持久化的信息要落到文件里，别光靠 AI 的短期记忆。



## 七、排查不生效的问题

如果你发现 AI 好像没在遵守 CLAUDE.md 里的规则，可以按这个顺序排查：

1）运行 `/memory` 命令，看看你的 CLAUDE.md 有没有被正确加载

2）检查指令是不是太模糊了。比如格式化好代码这种 AI 没法执行，改成使用 2 空格缩进、单行不超过 80 字符

3）检查不同文件之间有没有矛盾的指令。如果 CLAUDE.md 里说用 MyBatis Plus，某个 rules 文件里又说用 MyBatis Flex，AI 可能随便选一个

4）如果某个操作必须在特定时机执行，比如每次提交前跑 lint，就不要靠 CLAUDE.md 了，改用 Hooks

![](https://pic.yupi.icu/1/11_%E8%A7%84%E5%88%99%E4%B8%8D%E7%94%9F%E6%95%88%E6%8E%92%E6%9F%A5%E5%86%B3%E7%AD%96%E6%A0%91_compressed_v1.png)



## 写在最后

没想到吧，就这么一个 Markdown 文件，其实是 AI 编程时代最重要的基础设施之一。

以前我们写 README.md 是给人看的，现在写 CLAUDE.md 是给 AI 看的。但本质都一样，就是把项目的重要信息组织好、传达清楚。区别在于，给 AI 写的说明书要更精炼、更具体、更可执行。

另外补充一个好消息，前面讲的「删掉它 AI 会犯错吗」这个判断标准，现在有工具帮你做了。Claude Code 内置了一个 `/doctor` 命令，可以自动扫描你的 CLAUDE.md 和 Skills，把冗余内容和矛盾指令都揪出来。想了解这个命令的用法，可以阅读本目录中的《Claude Code 常用斜杠命令大全》。

如果你还没有为自己的项目写一份 CLAUDE.md，马上就可以试试。从最简单的 20 行开始，把技术栈、构建命令、和 AI 总是犯错的几个规则写进去，你会立刻感受到它的强大。